package info.pppc.pcom.system.model;

import info.pppc.base.system.event.IListener;
import info.pppc.pcom.system.model.contract.reader.IResourceProvisionReader;

/**
 * The element contract is a marker interface for all contracts. Contracts
 * describe the current environment of an element. Typcially, an element
 * can retrieve the demands directed to it (if any) and the provisions that
 * have been made available by the container.
 * 
 * @author Mac
 */
public interface IElementStatus {

	/**
	 * Signals that the resource provison changed. The event source will be the
	 * status and the event type will be an resource provision reader of the 
	 * provision that changed.
	 */
	public static final int EVENT_RESOURCE_CHANGED = 1;
	
	/**
	 * Signals that the resource provison changed. The event source will be the
	 * status and the event type will be an resource provision reader of the 
	 * provision that changed.
	 */
	public static final int EVENT_RESOURCE_REMOVED = 2;
	
	/**
	 * Adds a status listener to events generated by the status. Currently,
	 * the only event supported is EVENT_RESOURCE_CHANGED. 
	 * 
	 * @param types The types to register for. Multiple types can be registered
	 * 	using a logical or concatenation.
	 * @param listener The listener that will be notified.
	 */
	public void addStatusListener(int types, IListener listener);
	
	/**
	 * Removes a previously registered listener from the status for a
	 * specified set of events.
	 * 
	 * @param types The types to unregister.
	 * @param listener The listener to unregister.
	 * @return True if the listener has been unregistered, false otherwise.
	 */
	public boolean removeStatusListener(int types, IListener listener);
	
	/**
	 * Returns all resource provisions that are currently provided to the
	 * instance, resource, allocator or factory by the container. For instances, 
	 * the resource provisions correspond to the specified required resources. For 
	 * factories and allocators, the container cannot guarantee the availability 
	 * of all resources that are required. Thus, a factory or allocator must deal 
	 * with the unavailability of resources (e.g., by not creating any instances, 
	 * stopping existing instances, or disposing resources).
	 * 
	 * @return The resource provisions that are currently issued to the
	 * 	instance, factory, allocator or resource.
	 */
	public IResourceProvisionReader[] getResources();

	/**
	 * Returns the resource provision with a certain type. If the type is null, this 
	 * method will throw an exception. If the specified type does not exist, this method 
	 * will return null. 
	 * 
	 * @param name The type of the resource provision that should be retrieved.
	 * @return The resource provision with the specified type or null if the specified 
	 * 	type is not provided.
	 * @throws NullPointerException Thrown if the name is null.
	 */
	public IResourceProvisionReader getResource(String name);
	
}
